Skip to content

Add maintain commands for deployed-app items - #62

Draft
raghubetina wants to merge 2 commits into
mainfrom
maintain-command
Draft

raghubetina wants to merge 2 commits into
mainfrom
maintain-command

Conversation

@raghubetina

@raghubetina raghubetina commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds the firstdraft maintain group for the maintenance service in firstdraft/firstdraft#1290 (draft, API contract 0.8.1). Part of the maintenance package; draft until the owner reviews the package as a whole.

  • firstdraft maintain [--environment NAME] [--page N] reads one page of open items for the Project in .firstdraft/state.json (GET .../environments/:name/items?page=N). --environment defaults to production.
  • firstdraft maintain show ID [--environment NAME] reads one item with evidence and done_when.
  • firstdraft maintain resolve ID --reason REASON [--detail TEXT] [--environment NAME] posts {reason, detail?}. A reason other than pull_request, host_change, not_a_bug, duplicate, or stopped_occurring is invalid_arguments (exit 2) before any request.

All three accept --staging, authenticate through authenticateApiCommand, use the pinned origin, and print the validated response on stdout. Validation is exact-key, like compilation cancel: the Project ID, Environment name, and item ID must match the request, index items must be open, and a resolution must come back resolved with the sent reason. The CLI prints a fresh copy, so evidence.untrusted and evidence.note reach the agent unchanged.

New handled errors, in docs/errors.md:

  • maintain_rejected: a validated problem (environment_not_found, item_not_found, invalid_resolution_reason, item_already_resolved), with response.
  • maintain_unavailable: network failure, timeout, 408/5xx, or an error with no problem body. The Service refuses a second resolution, so retrying is safe; this follows the compilation_cancel_unavailable precedent rather than request_outcome_unknown.
  • invalid_maintain_response: a success response that breaks the contract.

Contract range (owner review)

The CLI never reads FirstDraft-API-Contract at run time. release/compatibility.json declares one range per CLI release, and the Service's release check compares it with Production. This PR raises requires.api_contract from >= 0.8.0 to >= 0.8.1 (keeping < 0.9.0), as step 7 of the add-a-command checklist says.

  • Other commands are unaffected at run time: against a 0.8.0 Service they behave exactly as before. Only the release check's view changes, and it now refuses to publish this CLI before Production serves 0.8.1.
  • Leaving the range at >= 0.8.0 would let the release check publish a CLI whose maintain cannot work. Against a 0.8.0 Service the routes do not exist and Rails answers 404 HTML without the contract header, so a run-time header check could not help. That case is maintain_unavailable with status: 404, and docs/errors.md explains it.
  • A range per command would need a new firstdraft.release-compatibility format in all three repositories.

The version stays 0.9.0; the version PR picks the next one.

Sibling changes

  • firstdraft/skills: add src/commands/maintain.js to packedFileAllowlist in script/cli-contract/config.mjs, raise the Skills API requirement to >= 0.8.1 when it bundles this CLI, and add the Skill's maintain guidance and error handling.

Docs: updated docs/commands.md (intro, command map, Maintain section, Service endpoints, add-a-command checklist), docs/errors.md (Maintenance recovery and the Error index rows), and README.md.

Review: Codex, approve (3 rounds, 2 findings fixed)

Validation

  • npm audit: 0 vulnerabilities
  • npm run check: passes (284 tests, pack check, packed smoke including maintain, show, and resolve against a local server)

Observed (2026-11-17): against a local service from firstdraft/firstdraft#1290 polling learn's production GlitchTip data, maintain, maintain show, maintain resolve, and a repeated resolve (409) behaved as documented; the run found the missing evidence.request.host, now added.

Second commit: summaries carry the nullable issue_url, the GitHub issue First Draft files and keeps current for the item (firstdraft/firstdraft#1296). The service files issues itself through the GitHub App (owner direction, 2026-11-17), so the CLI has no issue command.

Review (second commit): Codex, approve (1 round, no findings; an earlier maintain issue design went through 3 rounds before the direction changed)

@raghubetina
raghubetina force-pushed the maintain-command branch 3 times, most recently from f9ab7cb to cfcbf02 Compare November 17, 2026 07:39
The maintenance service (firstdraft/firstdraft#1290) gives the owner's
agent a queue of open items for each deployed Environment. The agent
needs to read that queue, see one item's evidence, and record how it
was resolved, so this adds firstdraft maintain, maintain show, and
maintain resolve against the API contract 0.8.1 routes.

Each response is checked against the exact contract and printed as a
fresh copy, so nothing unvalidated reaches stdout, while the
evidence's untrusted list and note pass through unchanged for the
agent. The Service refuses a second resolution with
item_already_resolved, so a repeat is safe and an unconfirmed
resolution is maintain_unavailable, not request_outcome_unknown.

The CLI never reads FirstDraft-API-Contract at run time, so only the
release check keeps this package from shipping ahead of a Service
with these routes. The required range rises to >= 0.8.1. The other
commands behave the same against a 0.8.0 Service; a range per command
would need a new compatibility format in all three repositories.

Only reads are called safe to retry. A recurrence can reopen an item
between a lost resolution response and its retry, so after an
unconfirmed resolution the agent rereads it with `maintain show`.
First Draft files and keeps a GitHub issue current for every item, as
Rollbar's and Honeybadger's GitHub integrations do. Summaries now carry
`issue_url`, so the agent can link the issue from its pull request
without managing the issue itself.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant